fix(plugin-chatbot): accept the AI SDK's UIMessage in the exported mappers - #8341

Fixes #8214

Spelling note, same reason the card gives: generic type arguments are written as WORDS below (UIMessage of unknown, UIDataTypes, UITools), because GitHub's body sanitizer eats tag-shaped fragments — backticks and fences included.

The defect

packages/plugin-chatbot/src/mapMessages.ts declares a deliberately permissive local AnyPart — every member is string / unknown — but typed one member against the output contract:

state?: ChatToolInvocation['state'];   // the TOOL-invocation lifecycle

@ai-sdk/react's text and reasoning parts carry state: 'streaming' | 'done', which is not in that union. So the interface written to absorb the SDK's part union was, on that one property, stricter than the union it exists to absorb, and the whole UIMessage[] assignment failed — at the exact call the docblock and the README export the mappers for.

The fix (PM ruling: option A)

AnyPart.state is now string, and the file's single read site narrows through a guard:

// a Record keyed by (NonNullable of ChatToolInvocation's state), valued true
const TOOL_STATES = { 'input-streaming': true, /* … the other 6 rows … */ };

// a type predicate narrowing to (NonNullable of ChatToolInvocation's state)
function isToolState(state) { return state !== undefined && state in TOOL_STATES; }

// the one read site, was: const persistedState = p.state;
const persistedState = isToolState(p.state) ? p.state : undefined;

Why string and not the union of both known state sets. Both widens cost the same at the read site — neither one lets p.state flow into ChatToolInvocation['state'] without an explicit narrowing, because AnyPart is a flat interface and the p.type filter above does not narrow a sibling property. Given equal cost, string is the one consistent with the ruling: it is a purely local widening. Enumerating one dependency's current literals inside a published parameter type keeps the type coupled to @ai-sdk/react@4.0.68 without the SDK's type as the source of truth — the coupling of option B with none of its authority — and re-creates this identical defect on the next SDK bump. string matches every sibling member of AnyPart and ends the class.

Cost at the read sites. mapMessages.ts has exactly one read of p.state (line 634 on the base; the other four state occurrences in extractToolInvocations are locals). It pays one guard call. The Record over the union is what keeps the guard honest in both directions: a typo in the table is a compile error, and a state added to ChatToolInvocation['state'] fails here until a row is added.

Behaviour fix that falls out of it. An unrecognized state string (an AI SDK v4 snapshot's 'result', say) used to pass through verbatim into ChatToolInvocation.state, then fall past every branch in getToolState and render a finished call as "Running" forever. It now normalizes to undefined, which is that function's documented "infer from errorText / result" case. The output type is now true at runtime instead of merely asserted.

Evidence

Instrument is the package's own type-check (tsc --noEmit && tsc -p tsconfig.test.json), not vitest — vitest transpiles types away. tsconfig.test.json was confirmed to actually read the test file (--listFiles, 1876 files, src/__tests__/mapMessages.test.ts present; a made-up filename control returns 0 hits).

Ablation discipline: mutation proved on disk by git hash-object differing from git rev-parse HEAD:PATH, restore proved by state (git diff HEAD empty and the hashes equal again), trap … EXIT INT TERM with absolute paths, from a committed implementation. A separate positive control confirms the vitest case is really executed: an injected failing expectation turns that exact file and test name red, then is restored by state.

The two load-bearing casts

• mapMessages.test.ts:135 msgs as never — removed. The fixture is now declared UIMessage[] imported from @ai-sdk/react, so the pin is about the dependency's real shape rather than a hand-rolled literal. Note the cast was doing more than the card's diagnostic: the untyped literal also had role: string, so the cast was hiding two things. The SDK type fixes both, and nothing else in the fixture had to change.
• useObjectChat.ts:683 chatResult as any — measured, left in place. With the widen applied, removing it leaves exactly one diagnostic, and it has nothing to do with this card: TS2322 at useObjectChat.ts:803 — the hook's own returned setMessages is declared (messages: unknown[]) => void while the SDK's is (messages: UIMessage[] | updater) => void, which is contravariantly incompatible. Out of scope here; reported rather than chased.

That measurement also substantiates the card's central claim rather than repeating it. With the narrow state restored and the as any removed, the mapper call in production source goes red too: TS2345 at useObjectChat.ts(701,69). So the widen fixes the package's own call site, not just the test — the as any had been masking this defect as well as the unrelated one.

README

The doc-snippet: fragment marker does exist on this base (packages/plugin-chatbot/README.md, line 361), so batch 30's PR #8228 has landed. It is removed here, and the doc-snippet gate is the instrument that proves the block now compiles:

Exit 1 is "I ran and found errors", not the exit 2 "PRECONDITION NOT MET" a fresh worktree gives before its closure is built; that closure (34 filters, from the gate's own --build-filter) was built for every one of these runs.

One addition beyond the brief: the seven-line prose blockquote directly above the marker — "Today this call needs a cast on the reader's side…" — is removed with it. It documents the defect as a live constraint on the reader; leaving it would keep the page telling readers to write a cast the compiler no longer wants, which is the same over-claim in prose that the marker was in metadata.

Changeset

minor on @object-ui/plugin-chatbot. Not breaking: the parameter type only got looser, so every argument that compiled before still compiles (verified — dist/mapMessages.d.ts now emits state?: string;). minor rather than patch because a published signature accepts input it previously refused, which is a capability a consumer can newly depend on. The repo forbids major; pnpm gate check-changeset-no-major is green, as are check-changeset-presence / -fixed / -overwrite.

Other gates run

check:control-bytes, check:readme-exports, check:doc-fences, check:doc-types, check:phantom-deps, check:unused-deps — all exit 0. check-governed-queue-guard --test on the four changed paths: NOT GOVERNED — 4 path(s) checked against 5 governed surface(s); none matched.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YBWFb5YgMU5dw8p2VKj16S

Generated by Claude Code